Skip to content

docs: bring the pages up to date with celeris v1.6.0 - #113

Draft
FumingPower3925 wants to merge 3 commits into
mainfrom
docs/v1-6-0-catch-up
Draft

FumingPower3925 wants to merge 3 commits into
mainfrom
docs/v1-6-0-catch-up

Conversation

@FumingPower3925

@FumingPower3925 FumingPower3925 commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Brings the pages up to date with what landed in celeris for v1.6.0 (celeris main at 42f096e0, https://github.com/goceleris/celeris). The site has no release-notes or migration page and its sidebar groups have no slot for one, so the changes go where each topic already lives, marked inline the way the site already does ("Since celeris v1.6.0", "Upgrading to v1.6.0"). No CHANGELOG (the docs repo has none). Celeris PRs and issues below are written as goceleris/celeris#N; nothing here closes them.

Statements come from the celeris godoc (config.go, server.go, driver/*, internal/mono, internal/engine/iouring/probe.go), the celeris README.md ("Busy polling (opt-in)") and the merged PR bodies. Numbers are the PRs' own measurements and are worded as such; none are invented.

Changes

Topic Page (section) Source
TCP_DEFER_ACCEPT default (about 1 s) and DisableDeferAccept; silent-connection bound configuration (Connection, socket, and I/O; ReadHeaderTimeout), engines (Epoll), performance (knobs) Config.DisableDeferAccept, Config.ReadHeaderTimeout godoc; goceleris/celeris#1193
epoll 25 ms sweep timer on every loop, timeouts on time with ReadHeaderTimeout: -1; io_uring sweep about 0.8 s configuration (new "How promptly the native engines enforce a timeout"), engines (Epoll) Config.ReadTimeout godoc; goceleris/celeris#1197 (before/after table)
Monotonic timeouts (internal/mono), suspend caveat configuration (same new section) internal/mono package doc; goceleris/celeris#1188 (release note, "Behaviour to know"), #1177
Shutdown per-engine contract by connection state (idle, request in progress, begun-but-incomplete head / bare CRLF, head in the kernel, silent) graceful-shutdown (new "What each kind of connection gets") Server.Shutdown godoc; goceleris/celeris#1208, #1220, #1226, #1243, #1253, #1225
io_uring look made once at the first drain pass, worker stops accepting while only the look is outstanding; 250 ms send-drain floor graceful-shutdown (What the drain waits for; new section) goceleris/celeris#1226, #1243 PR bodies; Server.Shutdown godoc
nil at the deadline does not mean nothing was cut graceful-shutdown (Shutdown sequence) Server.Shutdown godoc; goceleris/celeris#1225
Connection: close on every HTTP/1 response after Shutdown graceful-shutdown (new "Every HTTP/1 response after Shutdown ends its connection") Server.Shutdown godoc; goceleris/celeris#1169
PauseAccept lingers about 1.5 s with defer-accept on; DisableDeferAccept closes at once graceful-shutdown (Pause and resume accept) Server.PauseAccept godoc
Stuck-loop wedge bound max(WriteTimeout/2, 2 s) + WriteTimeout core-concepts (HTTP/2: a response write can wait for the client) Config.WriteTimeout godoc; goceleris/celeris#1202
Config.SocketBusyPoll (off by default, was 50 µs), validation error configuration (Connection, socket, and I/O; Validation), performance (knobs) Config.SocketBusyPoll godoc, internal/resource/config.go (Validate); goceleris/celeris#1227
Drivers follow the server's SocketBusyPoll; redis Config.SocketBusyPoll/WithSocketBusyPoll; postgres Connector.WithSocketBusyPoll; memcached has none; the v1.5 behaviour table data-stores (new "Busy polling for driver connections") celeris README "Busy polling (opt-in)"; Server.SocketBusyPoll godoc; goceleris/celeris#1233 PR body
redis handshake (HELLO) bounded by DialTimeout data-stores (Redis options) driver/redis Config.DialTimeout godoc; goceleris/celeris#1209
Cluster/Sentinel PubSub follows moves and failover; SSUBSCRIBE per slot and ErrCrossSlot; MOVED herd shares topology reads (200 to 2-6 CLUSTER SLOTS, the PR's fake-cluster measurement) data-stores (new "Redis Cluster and Sentinel") ClusterClient.Subscribe/SSubscribe godoc; goceleris/celeris#1154, #1210, #1211, #1215
One node Client per duplicated seed (ClusterClient) same goceleris/celeris#1241
SentinelClient.Close cancels and waits; NewSentinelClient discovery bounded at (N+1) x DialTimeout same SentinelClient.Close/NewSentinelClient godoc; goceleris/celeris#1247, #1251, #1252
postgres connect_timeout bounds dial plus startup, 10 s default when absent, =0 none, negative rejected data-stores (PostgreSQL) Options.ConnectTimeout godoc; goceleris/celeris#1216, #1223
memcached binary handshake bounded by DialTimeout; Config.Timeout per operation (3 s, negative none) data-stores (Memcached) Config.DialTimeout/Config.Timeout godoc; goceleris/celeris#1217, #1222
Closing a redis/memcached Client releases the standalone event loop data-stores (How colocation works) goceleris/celeris#1239
io_uring startup probes: transient failures not cached, Warn text engines (IOUring, new "Startup probes") probe.go (logPending); goceleris/celeris#1201, #1198
HTTP/2 on the native engines: ReadTimeout per request (408 + RST_STREAM(NO_ERROR), uploads must fit), ReadHeaderTimeout header block (GOAWAY(ENHANCE_YOUR_CALM)), IdleTimeout ignores PINGs configuration (new "HTTP/2 timeouts on the native engines") Config.ReadTimeout/Config.ReadHeaderTimeout godoc; goceleris/celeris#1150
epoll: a non-detached response is bounded by a minimum rate (64 KiB per WriteTimeout), no ceiling configuration (Timeouts, non-detached responses) Config.WriteTimeout godoc; goceleris/celeris#1119
static Root of ././ now serves the tree below it; hidden files not served by default (Dotfiles); filesystem root refused unless AllowFilesystemRoot; Server.Static has no opt-out static-files (callout under Static, static.Config table, pitfalls) Server.Static godoc, middleware/static Config.Root/Dotfiles/AllowFilesystemRoot godoc; goceleris/celeris#1152
Security fix: a static root made only of .. segments no longer serves files above it (v1.3.3 through v1.5.11); devices, FIFOs and sockets not served; Static missing file is 404 (was 500) static-files (callout under Static) goceleris/celeris#1152 release notes (PR body); Server.Static, Context.FileFromDir godoc
FileFromDir keeps serving hidden files and accepts a baseDir of ././// (v1.6.0) static-files (Safe directory serving) Context.FileFromDir godoc; goceleris/celeris#1152
cache Config.SetTimeout (new, default 1 s; an ignoring store may still write later; MemoryStore/MemoryKV unbounded) middleware-content (cache Config reference) middleware/cache Config.SetTimeout godoc; goceleris/celeris#1151

Corrections to existing text (not in the brief)

  • The epoll sweep interval was "up to about 0.1 s" in configuration (detached-stream table) and sse; it is 25 ms (Config.WriteTimeout godoc, epoll: the 25 ms sweep timer is armed on every loop, whatever the timeouts are (Refs #1194) celeris#1197).
  • configuration said each native-engine timeout fires within a sweep (about 30 ms on epoll); that holds for ReadTimeout and IdleTimeout only. WriteTimeout is judged in windows that end at a sweep (Config.ReadTimeout godoc), so a 1 s WriteTimeout closed a client that reads nothing at about 2 s in epoll: the 25 ms sweep timer is armed on every loop, whatever the timeouts are (Refs #1194) celeris#1197's measurement. Reworded.
  • data-stores "How colocation works" said that with WithEngine all driver FDs land on the server's worker goroutine; it now matches the busy-poll table (only Pub/Sub and Connector connections do on a started native server; commands and the Pool use netpoll; standalone loop before Start or on std). Sources: driver/redis/options.go (Config.SocketBusyPoll), driver/internal/eventloop/registry.go (Resolve).
  • engines FAQ and feature table listed accept control for every native engine; adaptive does not implement it.
  • core-concepts said an HTTP/2 window wait lasts at most WriteTimeout "for the whole response: progress does not extend it". Since engines: HTTP/2 WriteTimeout bounds a response that waits for the client's window, as a minimum rate: stage 2 of the per-stream deadlines (v1.6.0, Refs #889) celeris#1167 and #1180 it is a minimum rate with no ceiling; the paragraph now states the headline rule (the wedge bound above needs it) and not the full rule (Config.WriteTimeout godoc).
  • graceful-shutdown and engines said PauseAccept/ResumeAccept work on adaptive. The Server.ResumeAccept godoc says the Adaptive engine does not implement accept control and the calls return ErrAcceptControlNotSupported, and internal/adaptive/port_hold_internal_616_linux_test.go says the same. Since adaptive is the Linux default, a user must select epoll or io_uring to pause.

Where the brief and the source differ

  • The brief says std "resets a head in the kernel". The Server.Shutdown godoc says std reads the head after Shutdown began and drops it: the connection is closed without an answer, and reset only if body bytes are still unread (2 KiB measured gives a FIN, 64 KiB a reset). The page follows the godoc.
  • "Before" claims were checked against celeris v1.5.11 where the PR describes a regression: the epoll timerfd was gated on ReadHeaderTimeout > 0 and the io_uring probes were cached with sync.Once there; DisableDeferAccept and SocketBusyPoll are absent from v1.5.11's config.go.

Not documented / not placed

Test Plan

  • bun install --frozen-lockfile
  • bun run validate (9 cells, 0 errors)
  • bun run build (data layer, astro build, pagefind: 28 pages)
  • bun run check (0 errors, 0 warnings)
  • bun test (29 pass; includes the symbol-citation ratchet, no .go:N locators added)
  • Anchor sweep over the built dist/docs/*: every link and anchor this PR adds resolves
  • Looked at the affected pages in a browser (not done)

…own contract, busy poll, drivers)

The v1.6.0 changes that landed after the last docs sweep, each checked against
celeris main (42f096e0): TCP_DEFER_ACCEPT and DisableDeferAccept, Config.SocketBusyPoll
(off by default) and how the drivers follow it, the epoll 25 ms sweep timer, the
monotonic timeout clock, the per-engine Shutdown contract by connection state,
Connection: close after Shutdown, the stuck-loop wedge bound, and the redis,
postgres and memcached driver timeouts and lifecycle fixes.

Also corrects three statements the code does not match: the epoll sweep interval
(25 ms, not 0.1 s), the HTTP/2 window wait being an absolute WriteTimeout deadline
(it is a minimum rate), and PauseAccept/ResumeAccept working on adaptive (they
return ErrAcceptControlNotSupported there).
@FumingPower3925 FumingPower3925 added this to the v1.6.0 milestone Nov 4, 2026
@FumingPower3925 FumingPower3925 added the documentation Improvements or additions to documentation label Nov 4, 2026
@coderabbitai

coderabbitai Bot commented Nov 4, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 4, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
goceleris-docs a5ea41d Commit Preview URL

Branch Preview URL
Nov 04 2026, 01:54 AM

@codecov

codecov Bot commented Nov 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

…eep, colocation, accept control) and add the HTTP/2 deadlines, static Root and dotfiles, cache SetTimeout
…eFromDir, WriteTimeout example, version markers, cache SetTimeout)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant